home *** CD-ROM | disk | FTP | other *** search
/ Software Vault: The Diamond Collection / The Diamond Collection (Software Vault)(Digital Impact).ISO / cdr44 / bstrng11.zip / BSTRING.DOC < prev    next >
Text File  |  1995-01-28  |  14KB  |  511 lines
  1.  
  2.  
  3.  
  4.  
  5.  
  6.  
  7.  
  8.  
  9.  
  10.  
  11.  
  12.  
  13.  
  14.  
  15.  
  16.  
  17.  
  18.  
  19.  
  20.  
  21.  
  22.  
  23.  
  24.  
  25.  
  26.  
  27.  
  28.                            BSTRING PROGRAMMER'S MANUAL
  29.                                    VERSION 1.0
  30.  
  31.  
  32.                                 TechniLib Company
  33.  
  34.  
  35.  
  36.  
  37.  
  38.  
  39.  
  40.  
  41.  
  42.  
  43.  
  44.  
  45.  
  46.  
  47.  
  48.  
  49.  
  50.  
  51.  
  52.  
  53.  
  54.  
  55.  
  56.  
  57.  
  58.  
  59.  
  60.  
  61.  
  62.  
  63.                     Copyright 1995, by TechniLib (TM) Company
  64.                                All Rights Reserved
  65.  
  66.  
  67.  
  68.                           TERMS OF USE AND DISTRIBUTION
  69.  
  70.  
  71.        BSTRING is a shareware product; therefore, unregistered copies of BSTRING
  72.   are made available free of charge so that potential purchasers will have the
  73.   opportunity to examine and test the software before committing payment.
  74.   Distribution of unregistered copies of BSTRING to other potential users is
  75.   also permitted and appreciated.  However, usage and distribution of BSTRING
  76.   must conform to the following conditions.  In the following statement, the
  77.   term "commercial distribution," includes shareware distribution.
  78.  
  79.   1) BSTRING and accompanying software must be distributed together in copies of
  80.   the original archive provided by TechniLib.  Neither the archive nor
  81.   individual files therein may be modified.
  82.  
  83.   2) The BSTRING archive may be distributed in combination with other shareware
  84.   products; however, the BSTRING archive may not be distributed with other
  85.   commercially distributed software without written consent of TechniLib.
  86.  
  87.   3) Copies of BSTRING which have been used to develop software for commercial
  88.   distribution must be registered before such software is marketed.  Copies of
  89.   BSTRING which have been used to develop noncommercial software must be
  90.   registered if such software is to be regularly used either by the developer or
  91.   others.
  92.  
  93.   4) Commercially distributed software must embed BSTRING procedures in the
  94.   software code.  Files contained in the BSTRING archive may not be placed in
  95.   the distribution media.
  96.  
  97.   5) BSTRING is designed to offer a set of services to other executable code.
  98.   BSTRING may not be used to develop software for commercial distribution which
  99.   will essentially offer any of these same services to other executable code.
  100.   Exceptions to this condition require written consent of TechniLib.
  101.  
  102.   6) Rights afforded by registering a single copy of BSTRING pertain only to a
  103.   single computer.
  104.  
  105.   7) BSTRING may be registered for a fee of $10.00 per copy.  Consult README.DOC
  106.   in the BSTRING archive for further instructions regarding registration.
  107.  
  108.  
  109.                               DISCLAIMER OF WARRANTY
  110.  
  111.  
  112.        BSTRING AND ALL ACCOMPANYING SOFTWARE AND LITERATURE ARE DISTRIBUTED WITH
  113.   THE EXCLUSION OF ANY AND ALL IMPLIED WARRANTIES, AND WITH THE EXCLUSION OF
  114.   WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.  TechniLib
  115.   SHALL HAVE NO LIABILITY FOR SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES
  116.   RESULTING FROM THE USE OF BSTRING OR ACCOMPANYING MATERIALS.  The user assumes
  117.   the entire risk of using this software.
  118.  
  119.  
  120.  
  121.  
  122.  
  123.  
  124.  
  125.  
  126.                     Copyright 1995, by TechniLib (TM) Company
  127.                                All Rights Reserved
  128.  
  129.  
  130.  
  131.                                    Introduction
  132.                                    ------------
  133.  
  134.  
  135.        Though BASIC is not among the most powerful programming languages, it
  136.   does have the some of the most powerful string handling capabilities of all
  137.   languages.  BSTRING is a library of C functions which emulate the string
  138.   functions in BASIC.  Therefore, BSTRING not only provides a set of powerful
  139.   functions to C, but also simplifies the transition to C from BASIC.
  140.        All procedures in BSTRING are written in assembly language.  BSTRING
  141.   functions are therefore very compact and very fast.  In fact, they are faster
  142.   than analogous string functions in standard C libraries.  Speed improvements
  143.   are even more pronounced on Pentium processors because BSTRING code is
  144.   designed to fully utilize the superscalar architecture.
  145.        The BSTRING archive includes libraries for both Microsoft C and Borland
  146.   C.  Microsoft libraries are contained in MICROSOF.ZIP.  Borland libraries are
  147.   in BORLAND.ZIP.
  148.        To use BSTRING, the programmer should include the BSTRING.H header file
  149.   in their C program, and should link the program with the appropriate BSTRING
  150.   library.  The appropriate library will depend upon the memory model being
  151.   used.  The following is a list of available BSTRING libraries matched with
  152.   their corresponding memory models.
  153.  
  154.  
  155.   Library                     Memory Model
  156.   ------------                ------------
  157.   BSTRINGS.LIB                Small
  158.   BSTRINGC.LIB                Compact
  159.   BSTRINGM.LIB                Medium
  160.   BSTRINGL.LIB                Large and Huge
  161.  
  162.  
  163.  
  164.  
  165.  
  166.  
  167.  
  168.  
  169.  
  170.  
  171.  
  172.  
  173.  
  174.  
  175.  
  176.  
  177.  
  178.  
  179.  
  180.  
  181.  
  182.  
  183.  
  184.  
  185.  
  186.  
  187.  
  188.  
  189.  
  190.  
  191.                                         1
  192.  
  193.  
  194.  
  195.                              Detailed Specifications
  196.                              -----------------------
  197.  
  198.  
  199.        This section presents detailed descriptions of the various string
  200.   functions in BSTRING.  Each description includes a BASIC equivalent to the
  201.   BSTRING function.  These descriptions use variables which would be declared as
  202.   follows:
  203.  
  204.  
  205.   BASIC:
  206.  
  207.   DIM sstring AS STRING, dstring AS STRING
  208.   DIM start AS INTEGER, n AS INTEGER, ShortInt AS INTEGER, ASCIIcode as integer
  209.   DIM LongInt AS LONG
  210.   DIM DoubleFloat as DOUBLE
  211.  
  212.   C:
  213.  
  214.   char sstring[.], dstring[.];          /* Dimensions must be supplied */
  215.   int start, n, ShortInt, ASCIIcode;
  216.   long LongInt;
  217.   double DoubleFloat;
  218.  
  219.  
  220.        dstring is used in all of the following descriptions as the destination
  221.   string.  sstring is used as the source string.  If the destination string may
  222.   be modified by the function, then the function will always return the pointer
  223.   to this string.  The source string is never modified provided that it is
  224.   stored at a different location than the destination.  All BSTRING functions
  225.   are designed such that the source string and destination string may be equal.
  226.  
  227.  
  228.   Copy Strings
  229.   ------------
  230.  
  231.   BASIC: dstring = sstring
  232.   C:     movstr(dstring, sstring);
  233.  
  234.   PROTOTYPE: char* movstr(char* dstring, char* sstring);
  235.  
  236.  
  237.   Compute String Length
  238.   ---------------------
  239.  
  240.   BASIC: ShortInt = LEN(sstring)
  241.   C:     ShortInt = len(sstring);
  242.  
  243.   PROTOTYPE: int len(char* sstring);
  244.  
  245.   DETAILS: len returns 0 if sstring is null.
  246.  
  247.  
  248.  
  249.  
  250.  
  251.  
  252.  
  253.  
  254.  
  255.                                         2
  256.  
  257.  
  258.  
  259.   Add Strings
  260.   -----------
  261.  
  262.   BASIC: dstring = dstring + sstring
  263.   C:     addstr(dstring, sstring);
  264.  
  265.   PROTOTYPE: char* addstr(char* dstring, char* sstring);
  266.  
  267.   BASIC: dstring = sstring + dstring
  268.   C:     addstrr(dstring, sstring);        /* Add string reverse */
  269.  
  270.   PROTOTYPE: char* addstrr(char* dstring, char* sstring);
  271.  
  272.  
  273.   Get Characters from Left or Right of String
  274.   -------------------------------------------
  275.  
  276.   BASIC: dstring = LEFT$(sstring, n)
  277.   C:     left(dstring, sstring, n);
  278.  
  279.   PROTOTYPE: char* left(char* dstring, char* sstring, int n);
  280.  
  281.   BASIC: dstring = RIGHT$(sstring, n)
  282.   C:     right(dstring, sstring, n);
  283.  
  284.   PROTOTYPE: char* right(char* dstring, char* sstring, int n);
  285.  
  286.   DETAILS: If n = 0 (an invalid value), both left and right set dstring to null.
  287.   If n >= len(sstring), both left and right return dstring = sstring.
  288.  
  289.  
  290.   Get Characters Embedded in String
  291.   ---------------------------------
  292.  
  293.   BASIC: dstring = MID$(sstring, start, n)
  294.   C:     mid(dstring, sstring, start, n);
  295.  
  296.   BASIC: dstring = MID$(sstring, start)
  297.   C:     mid(dstring, sstring, start, -1);
  298.  
  299.   PROTOTYPE: char* mid(char* dstring, char* sstring, int start, int n);
  300.  
  301.   DETAILS: mid sets dstring to the n characters of sstring beginning with the
  302.   start character position.  Character positions are numbered 1 and upward.  If
  303.   sstring does not contain n characters from the start position, dstring is
  304.   terminated with the last character of sstring.
  305.      If start = 0 or n = 0 (invalid values), mid sets dstring to null.  If start
  306.   > len(sstring), mid sets dstring to null.
  307.      Under C++, either or both of start and n may be omitted.  If omitted, start
  308.   defaults to 1, and n defaults to -1 (0xffff).
  309.  
  310.  
  311.  
  312.  
  313.  
  314.  
  315.  
  316.  
  317.  
  318.  
  319.                                         3
  320.  
  321.  
  322.  
  323.   Compare Strings
  324.   ---------------
  325.  
  326.   BASIC: ShortInt = (dstring <= sstring) - (dstring >= sstring)
  327.   C:     ShortInt = cmpstr(dstring, sstring);
  328.  
  329.   PROTOTYPE: int cmpstr(char* dstring, char* sstring);
  330.  
  331.   DETAILS: cmpstr compares dstring to sstring.  If the strings are equal, cmpstr
  332.   returns 0.  If dstring is greater, cmpstr returns 1.  If sstring is greater,
  333.   cmpstr returns -1.  Neither string is modified.
  334.  
  335.  
  336.   Search for Substring
  337.   --------------------
  338.  
  339.   BASIC: ShortInt = INSTR(start, sstring, substring)
  340.   C:     ShortInt = instr(sstring, substring, start);
  341.  
  342.   BASIC: ShortInt = INSTR(sstring, substring)
  343.   C:     ShortInt = instr(sstring, substring, 1);
  344.  
  345.   PROTOTYPE: int instr(char* sstring, char* substring, int start);
  346.  
  347.   DETAILS: instr searches sstring for an occurrence of substring.  The search
  348.   begins at the character position supplied in start (first character = 1).  If
  349.   substring is found, instr returns the character position at which substring
  350.   begins.  Character positions are numbered 1 upward.  If substring is not
  351.   found, instr returns 0.
  352.      If start = 0 (an invalid value), instr returns 0.  If start > len(sstring),
  353.   instr returns 0.  If substring is null, instr returns start.
  354.      Under C++, start may be omitted, in which event, start defaults to 1.
  355.  
  356.  
  357.   Compute Value of Numeric String
  358.   -------------------------------
  359.  
  360.   BASIC: LongInt = VAL(sstring)
  361.   C:     LongInt = val(sstring);
  362.  
  363.   PROTOTYPE: long val(char* sstring);
  364.  
  365.   BASIC: LongInt = VAL(sstring);
  366.   C:     LongInt = valh(sstring);            /* sstring is hexadecimal */
  367.  
  368.   PROTOTYPE: long valh(char* sstring);
  369.  
  370.   BASIC: DoubleFloat = VAL(sstring);
  371.   C:     DoubleFloat = vald(sstring);
  372.  
  373.   PROTOTYPE: double vald(char* sstring);
  374.  
  375.   DETAILS: val will accept a hexadecimal string provided that it is prefixed
  376.   with 0x or 0X (e.g. 0xffff).  valh assumes a hexadecimal string with no
  377.   prefix.  Hexadecimal strings may use either upper or lower case letters.
  378.      vald will accept either standard or scientific notation.  vald uses numeric
  379.   processor instructions; therefore, a numeric processor must either be present
  380.   or an emulator must be installed.
  381.  
  382.  
  383.                                         4
  384.  
  385.  
  386.  
  387.   Convert Numeric to String
  388.   -------------------------
  389.  
  390.   BASIC: dstring = STR$(LongInt)
  391.   C:     str(dstring, LongInt);
  392.  
  393.   PROTOTYPE: char* str(char* dstring, long intnum);
  394.  
  395.   BASIC: dstring = HEX$(LongInt);
  396.   C:     hex(dstring, LongInt);
  397.  
  398.   PROTOTYPE: char* hex(char* dstring, long intnum);
  399.  
  400.   BASIC: dstring = STR$(DoubleFloat)
  401.   C:     strd(dstring, DoubleFloat, n);
  402.   C:     strds(dstring, DoubleFloat, n);
  403.  
  404.   PROTOTYPE: char* strd(char* dstring, double floatval, int decimals);
  405.   PROTOTYPE: char* strds(char* dstring, double floatval, int decimals);
  406.  
  407.   DETAILS: hex always returns a string 8 characters long.  The digits will
  408.   always be upper case.  No prefix is appended to the string.
  409.      strd returns dstring in standard notation whereas strds returns dstring in
  410.   scientific notation.  n specifies the number of decimal places.  For strds, n
  411.   specifies the number of decimal places in the mantissa.  strd cannot accept
  412.   numbers that are absolutely greater than or equal to 10 ^ 18.  In such cases,
  413.   the function will return dstring = "E" thereby indicating that strds must be
  414.   used.  strd and strds use numeric processor instructions; therefore, a numeric
  415.   processor must either be present or an emulator must be installed.
  416.  
  417.  
  418.   Remove Spaces from Right or Left of String
  419.   ------------------------------------------
  420.  
  421.   BASIC: dstring = LTRIM$(sstring)
  422.   C:     ltrim(dstring, sstring);
  423.  
  424.   PROTOTYPE: char* ltrim(char* dstring, char* sstring);
  425.  
  426.   BASIC: dstring = RTRIM$(sstring)
  427.   C:     rtrim(dstring, sstring);
  428.  
  429.   PROTOTYPE: char* rtrim(char* dstring, char* sstring);
  430.  
  431.  
  432.   Return String of Spaces
  433.   -----------------------
  434.  
  435.   BASIC: dstring = SPACE$(n);
  436.   C:     space(dstring, n);
  437.  
  438.   PROTOTYPE: char* space(char* dstring, int n);
  439.  
  440.   DETAILS: If n = 0 (invalid value), dstring is returned as null.
  441.  
  442.  
  443.  
  444.  
  445.  
  446.  
  447.                                         5
  448.  
  449.  
  450.  
  451.   Return String of Repeated Character
  452.   -----------------------------------
  453.  
  454.   BASIC: dstring = STRING$(n, ASCIIcode)
  455.   C:     string(dstring, n, ASCIIcode);
  456.  
  457.   PROTOTYPE: char* string(char* dstring, int n, int asciicode);
  458.  
  459.   DETAILS: If n = 0 (invalid value), dstring is returned as null.
  460.  
  461.  
  462.   Convert String to Lower or Upper Case
  463.   -------------------------------------
  464.  
  465.   BASIC: dstring = LCASE$(sstring)
  466.   C:     lcase(dstring, sstring);
  467.  
  468.   PROTOTYPE: char* lcase(char* dstring, char* sstring);
  469.  
  470.   BASIC: dstring = UCASE$(sstring)
  471.   C:     ucase(dstring, sstring);
  472.  
  473.   PROTOTYPE: char* ucase(char* dstring, char* sstring);
  474.  
  475.  
  476.   Justify String Within Fixed Field
  477.   ---------------------------------
  478.  
  479.   BASIC: dstring = SPACE$(n): LSET dstring = sstring
  480.   C:     lset(dstring, sstring, n);
  481.  
  482.   PROTOTYPE: char* lset(char* dstring, char* sstring, int n);
  483.  
  484.   BASIC: dstring = SPACE$(n): RSET dstring = sstring
  485.   C:     rset(dstring, sstring, n);
  486.  
  487.   PROTOTYPE: char* rset(char* dstring, char* sstring, int n);
  488.  
  489.   DETAILS: dstring is always returned with length n.  sstring is left-justified
  490.   or right-justified within dstring.  The remainder of dstring is filled with
  491.   spaces.  If len(sstring) >= n, both lset and rset return dstring =
  492.   left(sstring, n).
  493.      If n = 0 (invalid value), dstring is returned as null.
  494.      Observe that the LSET and RSET functions in BASIC implicitly set n =
  495.   len(dstring).
  496.  
  497.  
  498.  
  499.  
  500.  
  501.  
  502.  
  503.  
  504.  
  505.  
  506.  
  507.  
  508.  
  509.  
  510.  
  511.                                         6